---
title: act()
description: 'Complete API reference for the act() method'
icon: 'arrow-pointer'
---

<CardGroup cols={1}>
<Card title="Act" icon="arrow-pointer" href="/v2/basics/act">
  See how to use act() to perform browser actions
</Card>
</CardGroup>

### Method Signatures

<Tabs>
<Tab title="TypeScript">

```typescript
// String instruction
await page.act(instruction: string): Promise<ActResult>

// With ActOptions
await page.act(options: ActOptions): Promise<ActResult>

// Execute observed action
await page.act(observeResult: ObserveResult): Promise<ActResult>
```

**ActOptions Interface:**
```typescript
interface ActOptions {
  action: string;
  modelName?: AvailableModel;
  modelClientOptions?: ClientOptions;
  variables?: Record<string, string>;
  domSettleTimeoutMs?: number;
  timeoutMs?: number;
  iframes?: boolean;
}
```

</Tab>
<Tab title="Python">

```python
# String instruction
await page.act(instruction: str) -> ActResult

# With parameters
await page.act(
    instruction: str,
    variables: Dict[str, str] = None,
    dom_settle_timeout_ms: int = None,
    timeout_ms: int = None,
    model_name: AvailableModel = None,
    model_client_options: Dict = None,
    iframes: bool = None,
) -> ActResult

# Execute observed action
await page.act(observe_result: ObserveResult) -> ActResult
```

</Tab>
</Tabs>

### Parameters

<ParamField path="action" type="string" required>
  Natural language description of the action to perform.
</ParamField>

<ParamField path="variables" type="Record<string, string>" optional>
  Key-value pairs for variable substitution using `%variable%` syntax. Prevents sensitive data from appearing in logs.
</ParamField>

<ParamField path="modelName" type="AvailableModel" optional>
  Override the default LLM model for this action.
</ParamField>

<ParamField path="modelClientOptions" type="ClientOptions" optional>
  Model-specific configuration options.
  
  **Options:** `temperature`, `maxTokens`, `apiKey`
</ParamField>

<ParamField path="domSettleTimeoutMs" type="number" optional>
  Maximum time to wait for DOM to stabilize before attempting action.
  
  **Default:** `30000`
</ParamField>

<ParamField path="timeoutMs" type="number" optional>
  Maximum time to wait for the action to complete.
</ParamField>

<ParamField path="iframes" type="boolean" optional>
  Set to `true` if target element is within an iframe.
  
  **Default:** `false`
</ParamField>

<ParamField path="observeResult" type="ObserveResult" optional>
  Previously observed action to execute directly (enables self-healing).
</ParamField>

### Returns `Promise<ActResult>`

<ParamField path="success" type="boolean" required>
  Whether the action was completed successfully.
</ParamField>

<ParamField path="message" type="string" required>
  Details about the action's execution.
</ParamField>

<ParamField path="action" type="string" required>
  The action that was performed.
</ParamField>

```Example Response
{
  success: true,
  message: 'Action [scrollTo] performed successfully on selector: /html[1]',
  action: 'Scrollable area of the page where user can navigate to the pricing section or other parts of the page'
}
```

### Error Types

- **TimeoutError** - Action exceeded timeout limits
- **ElementNotFoundError** - Target element could not be located  
- **ActionFailedError** - Action could not be completed
- **StagehandError** - General Stagehand-specific errors